---
title: MCP 連携
description: Learn how to utilize MCP servers as tools
---

import { Code } from '@astrojs/starlight/components';
import hostedAgentExample from '../../../../../../examples/docs/mcp/hostedAgent.ts?raw';
import hostedExample from '../../../../../../examples/docs/mcp/hosted.ts?raw';
import hostedStreamExample from '../../../../../../examples/docs/mcp/hostedStream.ts?raw';
import hostedHITLExample from '../../../../../../examples/docs/mcp/hostedHITL.ts?raw';
import hostedConnectorExample from '../../../../../../examples/docs/mcp/hostedConnector.ts?raw';
import streamableHttpExample from '../../../../../../examples/docs/mcp/streamableHttp.ts?raw';
import stdioExample from '../../../../../../examples/docs/mcp/stdio.ts?raw';
import toolFilterExample from '../../../../../../examples/docs/mcp/tool-filter.ts?raw';

[**Model Context Protocol (MCP)**](https://modelcontextprotocol.io) は、アプリケーションが LLM にツールとコンテキストを提供する方法を標準化するオープンプロトコルです。MCP のドキュメントより:

> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンプロトコルです。MCP は AI アプリケーションにとっての USB‑C ポートのようなものだと考えてください。USB‑C がデバイスをさまざまな周辺機器やアクセサリに接続する標準化された方法を提供するように、MCP は AI モデルを異なるデータソースやツールに接続する標準化された方法を提供します。

この SDK がサポートする MCP サーバーは 3 種類あります:

1. **Hosted MCP server tools** – [OpenAI Responses API](https://platform.openai.com/docs/guides/tools-remote-mcp) によってツールとして使用されるリモート MCP サーバー
2. **Streamable HTTP MCP servers** – [Streamable HTTP トランスポート](https://modelcontextprotocol.io/docs/concepts/transports#streamable-http) を実装するローカルまたはリモートのサーバー
3. **Stdio MCP servers** – 標準入出力でアクセスするサーバー（最も簡単な選択肢）

ユースケースに応じてサーバータイプを選択します:

| 必要なこと                                                                                 | 推奨オプション          |
| ------------------------------------------------------------------------------------------ | ----------------------- |
| パブリックにアクセス可能なリモートサーバーをデフォルトの OpenAI responses モデルで呼び出す | **1. Hosted MCP tools** |
| パブリックにアクセス可能なリモートサーバーを使うが、ツール呼び出しはローカルでトリガーする | **2. Streamable HTTP**  |
| ローカルで動作する Streamable HTTP サーバーを使う                                          | **2. Streamable HTTP**  |
| OpenAI Responses 以外のモデルであらゆる Streamable HTTP サーバーを使う                     | **2. Streamable HTTP**  |
| 標準 I/O プロトコルのみをサポートするローカル MCP サーバーを使う                           | **3. Stdio**            |

## 1. Hosted MCP server tools

組み込みツール（Hosted）は、往復の処理全体をモデル側で行います。あなたのコードが MCP サーバーを呼び出す代わりに、OpenAI Responses API がリモートのツールエンドポイントを呼び出し、その結果をモデルにストリーミングします。

以下は hosted MCP ツールを使う最も簡単な例です。リモート MCP サーバーのラベルと URL を `hostedMcpTool` ユーティリティ関数に渡します。これは hosted MCP サーバーツールの作成に便利です。

<Code lang="typescript" code={hostedAgentExample} title="hostedAgent.ts" />

次に、`run` 関数（またはカスタマイズした `Runner` インスタンスの `run` メソッド）でエージェントを実行できます:

<Code lang="typescript" code={hostedExample} title="Hosted MCP ツールで実行" />

MCP の増分結果をストリーミングするには、`Agent` を実行するときに `stream: true` を渡します:

<Code
  lang="typescript"
  code={hostedStreamExample}
  title="Hosted MCP ツールで実行（ストリーミング）"
/>

#### 任意の承認フロー

機微な操作では、個々のツール呼び出しに人による承認を要求できます。`requireApproval: 'always'` か、ツール名から `'never'`/`'always'` への詳細なマッピングオブジェクトを渡します。

ツール呼び出しが安全かどうかをプログラムで判定できる場合は、[`onApproval` コールバック](https://github.com/openai/openai-agents-js/blob/main/examples/mcp/hosted-mcp-on-approval.ts) を使ってツール呼び出しを承認または拒否できます。人による承認が必要な場合は、ローカルの 関数ツール と同様に `interruptions` を使った同じ [人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop/) アプローチを使用できます。

<Code
  lang="typescript"
  code={hostedHITLExample}
  title="Hosted MCP ツールでの Human in the loop（人間の介入）"
/>

### コネクタ対応の hosted サーバー

Hosted MCP は OpenAI コネクタにも対応しています。`serverUrl` を指定する代わりに、コネクタの `connectorId` と `authorization` トークンを渡します。Responses API が認証を処理し、hosted MCP インターフェースを通じてコネクタのツールを公開します。

<Code
  lang="typescript"
  code={hostedConnectorExample}
  title="コネクタ対応の hosted MCP ツール"
/>

この例では、`GOOGLE_CALENDAR_AUTHORIZATION` 環境変数に Google OAuth Playground から取得した OAuth トークンを格納し、コネクタ対応サーバーが Calendar API を呼び出せるよう承認します。ストリーミングもあわせて実演する実行可能なサンプルは [`examples/connectors`](https://github.com/openai/openai-agents-js/tree/main/examples/connectors) を参照してください。

完全に動作するサンプル（Hosted ツール/Streamable HTTP/stdio + ストリーミング、HITL、onApproval）は、GitHub リポジトリの [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) にあります。

## 2. Streamable HTTP MCP servers

エージェントがローカルまたはリモートの Streamable HTTP MCP サーバーと直接通信する場合は、サーバーの `url`、`name`、必要に応じた設定で `MCPServerStreamableHttp` を初期化します:

<Code
  lang="typescript"
  code={streamableHttpExample}
  title="Streamable HTTP MCP サーバーで実行"
/>

このコンストラクタは、`authProvider`、`requestInit`、`fetch`、`reconnectionOptions`、`sessionId` などの MCP TypeScript SDK の追加オプションも受け付けます。詳細は [MCP TypeScript SDK リポジトリ](https://github.com/modelcontextprotocol/typescript-sdk) とそのドキュメントを参照してください。

## 3. Stdio MCP servers

標準 I/O のみを公開するサーバーでは、`fullCommand` を指定して `MCPServerStdio` を初期化します:

<Code lang="typescript" code={stdioExample} title="Stdio MCP サーバーで実行" />

## その他の知識

**Streamable HTTP** と **Stdio** のサーバーでは、`Agent` が実行されるたびに使用可能なツールを検出するために `list_tools()` を呼ぶ場合があります。この往復はレイテンシーを増やす可能性があり（特にリモートサーバーで）、`MCPServerStdio` または `MCPServerStreamableHttp` に `cacheToolsList: true` を渡すことで結果をメモリにキャッシュできます。

ツール一覧が変わらないと確信できる場合にのみ有効化してください。後からキャッシュを無効化するには、サーバーインスタンスで `invalidateToolsCache()` を呼びます。

### ツールのフィルタリング

`createMCPToolStaticFilter` による静的フィルター、またはカスタム関数を渡すことで、各サーバーから公開されるツールを制限できます。以下は両方のアプローチを示す統合例です:

<Code
  lang="typescript"
  code={toolFilterExample}
  title="ツールのフィルタリング"
/>

## 参考資料

- [Model Context Protocol](https://modelcontextprotocol.io/) – 公式仕様
- [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) – 上記で参照した実行可能デモ
